home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 3 / Cream of the Crop 3.iso / clipper / ks94an.zip / SKIPNEXT.HDR < prev    next >
Text File  |  1994-04-25  |  3KB  |  91 lines
  1. /******************************************************************************
  2.                  The Klipper Library, for CA-Clipper 5.x
  3.         Copyright (c), 1994, Wallace Information Systems Engineering
  4.  
  5. FUNCTION:
  6.  
  7. _Skip2Next( cField ) --> lIsEOF()
  8.  
  9. PARAMETERS:
  10.  
  11. cField : The NAME of a field to skip until value changes
  12.  
  13. SHORT:
  14.  
  15. Skip to the next index key value in a database.
  16.  
  17. DESCRIPTION:
  18.  
  19. _Skip2Next() is very simple, but also very time saving.  It looks at the
  20. field NAMED in the cField parameter and makes note of it's value.  It
  21. then SKIPS records until that field's value changes.
  22.  
  23. It is most useful where you want to do something with only one (unique)
  24. value from a group of values.  Anyone who has ever written a few lines of
  25. code to simply skip records until a new key value comes up in an index
  26. knows what this function is for.
  27.  
  28. Because of the potential disaster involved with specifying data instead of
  29. an actual field name, or mistakenly specifying a field name that does
  30. not exist (or exists but not in the current work area) the field
  31. name specified in cField is validated and if it does not exist in the
  32. current working database, the program is terminated by an internal call
  33. to _Terminate().
  34.  
  35. _Skip2Next() returns TRUE if you skipped off the end of the database
  36. while SKIPping/looking for a new field value. Otherwise it returns FALSE.
  37.  
  38. NOTE:
  39.  
  40.  
  41.  
  42. EXAMPLE:
  43.  
  44. _Skip2Next('LNAME')
  45.  
  46. LNAME   FNAME
  47. ------------------------------------------------
  48. SMITH   John       <- Record Pointer Before Call
  49. SMITH   Frank
  50. SMITH   Wesson
  51. SMITH   Blair
  52. SMYTHE  Jackie     <- Record Pointer After Call
  53. SMYTHE  Orlando
  54.  
  55. Make sure that you are skipping based on a field that has some order to it.
  56. Consider...
  57.  
  58. _Skip2Next('FNAME')
  59.  
  60. LNAME   FNAME
  61. ------------------------------------------------
  62. SMITH   John       <- Record Pointer Before Call
  63. SMITH   Frank      <- Record Pointer After Call
  64. SMITH   Wesson
  65. SMITH   Blair
  66. SMYTHE  Jackie
  67. SMYTHE  Orlando
  68.  
  69. And of course, be especially careful with:
  70.  
  71. _Skip2Next('M_INIT')
  72.  
  73. LNAME   FNAME
  74. ------------------------------------------------
  75. SMITH   John       <- Record Pointer Before Call
  76. SMITH   Frank
  77. SMITH   Wesson
  78. SMITH   Blair
  79. SMYTHE  Jackie
  80. SMYTHE  Orlando
  81.  
  82. <BEEP!>
  83. Error: Undefined Field specified in call to _SKIP2NEXT: YourApp Line 287
  84. C:\YOURAPP>
  85. C:\YOURAPP> <blink, blink, blink, blink...>
  86.  
  87. That's right, if you specify a field that doesn't exist, it cannot very well
  88. skip to the next one, now can it?
  89.  
  90. ******************************************************************************/
  91.